home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tclx / Memory.man < prev    next >
Encoding:
Text File  |  1992-03-20  |  12.9 KB  |  331 lines
  1.  
  2.  
  3.  
  4. Memory                C Library Procedures                 Memory
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      ckalloc, memory, ckfree, Tcl_DisplayMemory,  Tcl_InitMemory,
  12.      Tcl_ValidateAllMemory  -  Validated memory allocation inter-
  13.      face.
  14.  
  15. SSYYNNOOPPSSIISS
  16.      mmeemmoorryy iinnffoo
  17.      mmeemmoorryy ttrraaccee [oonn||ooffff]
  18.      mmeemmoorryy vvaalliiddaattee [oonn||ooffff]
  19.      mmeemmoorryy ttrraaccee__oonn__aatt__mmaalllloocc _n_n_n
  20.      mmeemmoorryy bbrreeaakk__oonn__mmaalllloocc _n_n_n
  21.      mmeemmoorryy ddiissppllaayy _f_i_l_e
  22.  
  23.  
  24.      ##iinncclluuddee <<ttccll..hh>> or <<cckkaalllloocc..hh>>
  25.  
  26.      char *
  27.      cckkaalllloocc (_s_i_z_e)
  28.  
  29.      void
  30.      cckkffrreeee (_p_t_r)
  31.  
  32.      void
  33.      TTccll__DDiissppllaayyMMeemmoorryy (fileName)
  34.  
  35.      void
  36.      TTccll__IInniittMMeemmoorryy (_i_n_t_e_r_p)
  37.  
  38.      void
  39.      TTccll__VVaalliiddaatteeAAllllMMeemmoorryy (_f_i_l_e, _l_i_n_e)
  40.  
  41. AARRGGUUMMEENNTTSS
  42.      uint         _s_i_z_e        (in)      The size  of  the  memory
  43.                                         block to be allocated.
  44.  
  45.      char         *_p_t_r        (in)      The address of a block to
  46.                                         free,   as   returned  by
  47.                                         ckalloc.
  48.  
  49.      Tcl_Interp   *_i_n_t_e_r_p     (in)      A  pointer  to  the   Tcl
  50.                                         interpreter.
  51.  
  52.      char         *_f_i_l_e       (in)      The   filename   of   the
  53.                                         caller                 of
  54.                                         Tcl_ValidateAllMemory.
  55.  
  56.      int          _l_i_n_e        (in)      The line  number  of  the
  57.                                         caller                 of
  58.                                         Tcl_ValidateAllMemory.
  59.  
  60.  
  61.  
  62.  
  63. Sprite v1.0                                                     1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Memory                C Library Procedures                 Memory
  71.  
  72.  
  73.  
  74.      char         *_f_i_l_e_N_a_m_e   (in)      File to display  list  of
  75.                                         active memory.
  76. _________________________________________________________________
  77.  
  78.  
  79. DDEESSCCRRIIPPTTIIOONN
  80.      The macro cckkaalllloocc allocates memory, in the  same  manner  as
  81.      mmaalllloocc,  with the following differences: One, cckkaalllloocc checks
  82.      the value returned from mmaalllloocc (it calls mmaalllloocc for you) and
  83.      panics  if the allocation request fails.  Two, if enabled at
  84.      compile time, a  version  of  cckkaalllloocc  with  special  memory
  85.      debugging  capabilities replaces the normal version of cckkaall--
  86.      lloocc, which aids in detecting  memory  overwrites  and  leaks
  87.      (repeated allocations not matched by corresponding frees).
  88.  
  89.      cckkffrreeee frees memory allocated  by  cckkaalllloocc.   Like  cckkaalllloocc,
  90.      when  memory debugging is enabled, cckkffrreeee has enhanced capa-
  91.      bilities for detecting memory overwrites and leaks.
  92.  
  93.      It is very important that you use cckkaalllloocc when you  need  to
  94.      allocate memory, and that you use cckkffrreeee to free it.  Should
  95.      you use mmaalllloocc to allocate  and  cckkffrreeee  to  free,  spurious
  96.      memory validation errors will occur when memory debugging is
  97.      enabled.  Should you use ffrreeee to free  memory  allocated  by
  98.      cckkaalllloocc,  memory corruption will occur when memory debugging
  99.      is enabled.  Any memory that is to be become the property of
  100.      the Tcl interpreter, such as result space, must be allocated
  101.      with cckkaalllloocc.  If it is absolutely necessary for an applica-
  102.      tion  to pass back mmaalllloocced memory to Tcl, it will work only
  103.      if Tcl is complied with the TTCCLL__MMEEMM__DDEEBBUUGG flag  turned  off.
  104.      If  you  convert  your  application to use this facility, it
  105.      will help you find memory over runs and lost  memory.   Note
  106.      that memory allocated by a C library routine requiring free-
  107.      ing should still be freed with ffrreeee, since it  calls  mmaalllloocc
  108.      rather than cckkaalllloocc to do the allocation.
  109.  
  110. FFIINNDDIINNGG MMEEMMOORRYY LLEEAAKKSS
  111.      The function TTccll__DDiissppllaayyMMeemmoorryy will display a  list  of  all
  112.      currently  allocated memory to the specified file.  The fol-
  113.      lowing information is displayed for each allocated block  of
  114.      memory:  starting  and  ending  addresses  (excluding  guard
  115.      zone), size, source file where cckkaalllloocc was called  to  allo-
  116.      cate  the  block  and line number in that file.  It is espe-
  117.      cially useful to call TTccll__DDiissppllaayyMMeemmoorryy after the Tcl inter-
  118.      preter has been deleted.
  119.  
  120. EENNAABBLLIINNGG MMEEMMOORRYY DDEEBBUUGGGGIINNGG
  121.      To enable memory debugging, Tcl should  be  recompiled  from
  122.      scratch  with TTCCLL__MMEEMM__DDEEBBUUGG defined.  This will also compile
  123.      in a non-stub version of TTccll__IInniittMMeemmoorryy to  add  the  mmeemmoorryy
  124.      command to Tcl.
  125.  
  126.  
  127.  
  128.  
  129. Sprite v1.0                                                     2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Memory                C Library Procedures                 Memory
  137.  
  138.  
  139.  
  140.      TTCCLL__MMEEMM__DDEEBBUUGG must be either left defined for all modules or
  141.      undefined  for  all  modules  that  are  going  to be linked
  142.      together.  If they are not, link  errors  will  occur,  with
  143.      either  TTccllDDbbCCkkffrreeee  and  TTccll__DDbbCCkkaalllloocc  or  TTccll__CCkkaalllloocc and
  144.      TTccll__CCkkffrreeee being undefined.
  145.  
  146. GGUUAARRDD ZZOONNEESS
  147.      When memory debugging is enabled, whenever a call to cckkaalllloocc
  148.      is made, slightly more memory than requested is allocated so
  149.      the memory debugging code can keep track  of  the  allocated
  150.      memory,  and  also  eight-byte ``guard zones'' are placed in
  151.      front of and behind the space that will be returned  to  the
  152.      caller.   (The  size  of  the guard zone is defined by the C
  153.      #define GGUUAARRDD__SSIIZZEE in _b_a_s_e_l_i_n_e/_s_r_c/_c_k_a_l_l_o_c._c --  it  can  be
  154.      extended  if  you  suspect large overwrite problems, at some
  155.      cost in performance.)  A known pattern is written  into  the
  156.      guard zones and, on a call to cckkffrreeee, the guard zones of the
  157.      space being freed are checked to see if either zone has been
  158.      modified  in  any way.  If one has been, the guard bytes and
  159.      their  new  contents  are  identified,  and  a  ``low  guard
  160.      failed''  or  ``high  guard failed'' message is issued.  The
  161.      ``guard failed'' message includes the address of the  memory
  162.      packet  and  the  file name and line number of the code that
  163.      called cckkffrreeee.  This allows you to detect the  common  sorts
  164.      of one-off problems, where not enough space was allocated to
  165.      contain the data written, for example.
  166.  
  167. TTHHEE MMEEMMOORRYY CCOOMMMMAANNDD
  168.      mmeemmoorryy _o_p_t_i_o_n_s
  169.           The Tcl mmeemmoorryy command gives the Tcl developer  control
  170.           of  Tcl's  memory  debugging  capabilities.  The memory
  171.           command has several  suboptions,  which  are  described
  172.           below.  It is only available when Tcl has been compiled
  173.           with memory debugging enabled.
  174.  
  175.      mmeemmoorryy iinnffoo
  176.           Produces a report containing the total allocations  and
  177.           frees  since  Tcl  began, the current packets allocated
  178.           (the current number of calls to cckkaalllloocc not  met  by  a
  179.           corresponding  call to cckkffrreeee), the current bytes allo-
  180.           cated, and the maximum  number  of  packets  and  bytes
  181.           allocated.
  182.  
  183.      mmeemmoorryy ttrraaccee [oonn||ooffff]
  184.           Turns memory tracing on or off.  When memory tracing is
  185.           on, every call to cckkaalllloocc causes a line of trace infor-
  186.           mation to be written to _s_t_d_e_r_r, consisting of the  word
  187.           _c_k_a_l_l_o_c,  followed  by the address returned, the amount
  188.           of memory allocated, and the C filename and line number
  189.           of the code performing the allocation, for example...
  190.  
  191.              cckkaalllloocc 4400ee447788 9988 ttccllPPrroocc..cc 11440066
  192.  
  193.  
  194.  
  195. Sprite v1.0                                                     3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. Memory                C Library Procedures                 Memory
  203.  
  204.  
  205.  
  206.           Calls to cckkffrreeee are traced in the same  manner,  except
  207.           that the word _c_k_a_l_l_o_c is replaced by the word _c_k_f_r_e_e.
  208.  
  209.      mmeemmoorryy vvaalliiddaattee [oonn||ooffff]
  210.           Turns memory vaidation on or off.  When memory  valida-
  211.           tion  is  enabled,  on every call to cckkaalllloocc or cckkffrreeee,
  212.           the guard zones are checked for every piece  of  memory
  213.           currently  in  existence that was allocated by cckkaalllloocc.
  214.           This has a large performance impact and should only  be
  215.           used  when  overwrite  problems are strongly suspected.
  216.           The advantage of enabling memory validation is  that  a
  217.           guard  zone overwrite can be detected on the first call
  218.           to cckkaalllloocc or  cckkffrreeee  after  the  overwrite  occurred,
  219.           rather than when the specific memory with the overwrit-
  220.           ten guard zone(s) is freed, which may occur long  after
  221.           the overwrite occurred.
  222.  
  223.      mmeemmoorryy ttrraaccee__oonn__aatt__mmaalllloocc _n_n_n
  224.           Enable memory tracing after _n_n_n cckkaallllooccss have been per-
  225.           formed.     For    example,   if   you   enter   mmeemmoorryy
  226.           ttrraaccee__oonn__aatt__mmaalllloocc 110000, after the 100th call  to  cckkaall--
  227.           lloocc,   memory   trace   information  will  begin  being
  228.           displayed for all allocations and frees.   Since  there
  229.           can  be  a  lot  of  memory  activity  before a problem
  230.           occurs, judicious use of this  option  can  reduce  the
  231.           slowdown  caused  by  tracing  (and the amount of trace
  232.           information produced), if you can identify a number  of
  233.           allocations that occur before the problem sets in.  The
  234.           current number of memory allocations that have  occured
  235.           since Tcl started is printed on a guard zone failure.
  236.  
  237.      mmeemmoorryy bbrreeaakk__oonn__mmaalllloocc _n_n_n
  238.           After the nnnnnn allocations have been performed, cckkaallllooccss
  239.           output  a  message  to  this  effect and that it is now
  240.           attempting to enter the  C  debugger.   Tcl  will  then
  241.           issue  a _S_I_G_I_N_T signal against itself.  If you are run-
  242.           ning Tcl under a C debugger, it should then  enter  the
  243.           debugger command mode.
  244.  
  245.      mmeemmoorryy ddiissppllaayy _f_i_l_e
  246.           Write a list of all currently allocated memory  to  the
  247.           specified file.
  248.  
  249. DDEEBBUUGGGGIINNGG DDIIFFFFIICCUULLTT MMEEMMOORRYY CCOORRRRUUPPTTIIOONN PPRROOBBLLEEMMSS
  250.      Normally, Tcl compiled with memory  debugging  enabled  will
  251.      make  it  easy  to isolate a corruption problem.  Turning on
  252.      memory validation with the memory command can  help  isolate
  253.      difficult  problems.   If you suspect (or know) that corrup-
  254.      tion is occurring before the Tcl interpreter  comes  up  far
  255.      enough  for  you to issue commands, you can set MMEEMM__VVAALLIIDDAATTEE
  256.      define, recompile tclCkalloc.c and rebuild Tcl.   This  will
  257.      enable  memory  validation  from  the first call to cckkaalllloocc,
  258.  
  259.  
  260.  
  261. Sprite v1.0                                                     4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. Memory                C Library Procedures                 Memory
  269.  
  270.  
  271.  
  272.      again, at a large performance impact.
  273.  
  274.      If you are desperate and validating memory on every call  to
  275.      cckkaalllloocc  and  cckkffrreeee  isn't  enough, you can explicitly call
  276.      TTccll__VVaalliiddaatteeAAllllMMeemmoorryy directly at any  point.   It  takes  a
  277.      _c_h_a_r  *  and an _i_n_t which are normally the filename and line
  278.      number of the caller, but they can actually be anything  you
  279.      want.  Remember to remove the calls after you find the prob-
  280.      lem.
  281.  
  282. KKEEYYWWOORRDDSS
  283.      ckalloc, ckfree, free, memory, malloc
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327. Sprite v1.0                                                     5
  328.  
  329.  
  330.  
  331.